Draft

3 January 2023

Editors:

  • Jeffrey Mates

Additional artifacts:

This prose specification is one component of a Work Product that also includes:

  • STIX™ Version 2.1 - OS

Related work:

This specification replaces or supersedes:

  • N/A

Abstract:

The current STIX 2.1 Identity object only contains a single text field for contact information. This is insufficient to effectively move contact information for individuals between automated systems. This extension adds more granular tracking so that this can be effectively communicated between systems.

1. Identity Contact Information Extension

The properties and additional types within the Identity Contact Information Extension are defined below. As this is not a top-level object, fields such as identifier are not present. This extension should be mapped to extension-definition—​66e2492a-bbd3-4be6-88f5-cc91a017a498.

At least one of the following properties/sets of properties MUST be provided:

  • contact_numbers

  • email_addresses

  • social_media_accounts

Property Name Type Description

extension_type (required)

string

The value of this property MUST be property-extension

contact_numbers (optional)

list of type contact-numer

A list of contact number objects that contain the phone and fax numbers.

email_addresses (optional)

list of type email-contact

A list of contact number objects that contain the phone and fax numbers.

first_name (optional)

string

The first name of an individual.

last_name (optional)

string

The last name of an individual.

middle_name (optional)

string

The middle name of an individual.

prefix (optional)

string

A prefix or title for an individual such as “Mr” or “Ms”.

social_media_accounts (optional)

list of type social-media-contact

A list of social media contact objects that contain the social media account type and account.

suffix (optional)

string

A suffix for the individual such as “PhD”.

2. Additional Sub-Object Types

2.1. Contact Number Object Type

Type Name: contact-number

Property Name Type Description

description (optional)

string

An additional description for the phone number and its purpose.

classified (optional)

boolean

Can be used to reach the identity on a classified phone. The default is false.

contact_number_type (required)

open_vocab

The type of number this is used for. This SHOULD be drawn from contact-number-ov.

contact_number (required)

string

The contact number. Typically a phone number.

2.2. Email Contact Object Type

Type Name: email-contact

Property Name Type Description

description (optional)

string

An additional description for the email and its purpose.

classified (optional)

boolean

Can be used to reach the identity on a classified network. The default is false.

digital_contact_type (required)

open_vocab

The type of email that address is used for. This SHOULD be drawn from digital-contact-ov.

email_address_ref (required)

identifer of type email-addr

A reference to the email address itself.

2.3. Social Media Contact Object Type

Type Name: social-media-contact

Property Name Type Description

description (optional)

string

An additional description for the social media account and its purpose

classified (optional)

boolean

Can be used to reach the identity on a classified network. The default is false.

digital_contact_type (required)

open_vocab

The type of social media account that relates to. This SHOULD be drawn from digital-contact-ov.

This SHOULD NOT be used to capture the social media service used. That SHOULD be encoded into the User Account Object that is linked to by the user_account_ref property.

user_account_ref (required)

identifer of type user-account

A reference to the social media account itself.

3. Vocabularies

3.1. Contact Number Type Vocabulary

Type Name: contact-number-ov

Vocabulary Value Description

personal-landline-phone

A personal landline phone number

personal-mobile-phone

A personal mobile phone number.

personal-fax

A personal fax number

work-phone

A work phone number (landline or mobile)

work-fax

A work fax number

3.2. Digital Contact Type Vocabulary

Type Name: digital-contact-ov

Vocabulary Value Description

organizational

A shared email address/user-id for an organization.

personal

A personal email address/user-id.

work

A work email address/user-id.

4. Identity Contact Information Examples

4.1. Identitiy Contact Details Example

{
    "type": "bundle",
    "id": "bundle--bac5c97c-3a7f-481c-aa42-b0e7465a67dc",
    "objects": [
        {
            "type": "identity",
            "id": "identity--32a6ff61-167a-4481-b678-38e20b1989dc",
            "created": "2023-08-06T01:02:00.000Z",
            "modified": "2023-11-16T01:03:01.000Z",
            "spec_version": "2.1",
            "name": "Michael Michaelson",
            "description": "a contact person",
            "identity_class": "individual",
            "contact_information": "102-030-4050 / m.michaelson@address.com",
            "extensions": {
                "extension-definition--66e2492a-bbd3-4be6-88f5-cc91a017a498": {
                    "extension_type": "property-extension",
                    "first_name": "Michael",
                    "middle_name": "Mikael",
                    "last_name": "Michaelson",
                    "prefix": "Dr",
                    "suffix": "PhD",
                    "contact_numbers": [
                        {
                            "contact_number": "102-030-4050",
                            "contact_number_type": "personal-landline-phone",
			                "classified": false
                        },
                        {
                            "contact_number": "203-040-5060",
                            "contact_number_type": "work-phone",
                            "classified": false
                        },
                        {
                            "contact_number": "304-050-6070",
                            "contact_number_type": "personal-mobile-phone",
                            "classified": true
                        }
                    ],
                    "email_addresses": [
                        {
                            "email_address_ref": "email-addr--d80eb6d5-7d01-4cd2-b710-20ac765dc9c5",
                            "digital_contact_type": "personal",
                            "classified": false
                        },
                        {
                            "email_address_ref": "email-addr--04aceb6b-f47f-4e6d-8de1-591961aa46d5",
                            "digital_contact_type": "work",
                            "classified": false
                        },
                        {
                            "email_address_ref": "email-addr--1f081efd-856b-4ae3-a242-688a6c223fae",
                            "digital_contact_type": "work",
                            "classified": true
                        }
                    ],
                    "social_media_accounts": [
                        {
                            "user_account_ref": "user-account--a60d5641-a860-4a86-8ed8-6bbbeaf300e9",
                            "digital_contact_type": "personal",
                            "description": "Michael Michaelson's personal social media account",
                            "classified": false
                        }
                    ]
                }
            }
        },
        {
            "type": "email-addr",
            "spec_version": "2.1",
            "id": "email-addr--d80eb6d5-7d01-4cd2-b710-20ac765dc9c5",
            "value": "m.michaelson@address.com"
        },
        {
            "type": "email-addr",
            "spec_version": "2.1",
            "id": "email-addr--04aceb6b-f47f-4e6d-8de1-591961aa46d5",
            "value": "michaelson@workaddress.com"
        },
        {
            "type": "email-addr",
            "spec_version": "2.1",
            "id": "email-addr--1f081efd-856b-4ae3-a242-688a6c223fae",
            "value": "michaelson@classifiedworkaddress.com" 
        },
        {
            "type": "user-account",
            "spec_version": "2.1",
            "id": "user-account--a60d5641-a860-4a86-8ed8-6bbbeaf300e9",
            "account_login": "mmichaelson",
            "account_type": "social media service"
        }
    ]
}

4.2. Organization Contact Details Example

{
    "type": "bundle",
    "id": "bundle--bac5c97c-3a7f-481c-aa42-b0e7465a67dc",
    "objects": [
        {
            "type": "identity",
            "id": "identity--361ef301-c0cf-4b92-9d42-d2424c47f31d",
            "created": "2023-01-06T01:02:00.000Z",
            "modified": "2023-10-16T01:03:01.000Z",
            "spec_version": "2.1",
            "name": "Test Company",
            "description": "a company",
            "identity_class": "organization",
            "extensions": {
                "extension-definition--66e2492a-bbd3-4be6-88f5-cc91a017a498": {
                    "extension_type": "property-extension",
                    "contact_numbers": [
                        {
                            "contact_number": "456-789-1234",
                            "contact_number_type": "work-phone",
			                "classified": false
                        }
                    ],
                    "email_addresses": [
                        {
                            "email_address_ref": "email-addr--035f27c3-0bb7-4400-b270-46cba4a86663",
                            "digital_contact_type": "organizational",
                            "classified": false
                        }
                    ],
                    "social_media_accounts": [
                        {
                            "user_account_ref": "user-account--30e60bb2-3efd-4897-a6be-e0ced69920e7",
                            "digital_contact_type": "organizational",
                            "description": "Test Company's organizational social media account",
                            "classified": false
                        }
                    ]
                }
            }
        },
        {
            "type": "email-addr",
            "spec_version": "2.1",
            "id": "email-addr--035f27c3-0bb7-4400-b270-46cba4a86663",
            "value": "info@testcompany.com"
        },
        {
            "type": "user-account",
            "spec_version": "2.1",
            "id": "user-account--30e60bb2-3efd-4897-a6be-e0ced69920e7",
            "account_login": "testcompany",
            "account_type": "social media service"
        }
    ]
}

Appendix A. Acknowledgements

Primary Editor

Jeffrey Mates, US Department of Defense (DoD)

Contributors The following individuals were members of the OASIS CTI Technical Committee and contributed time and effort to ensure that this extension would be possible. Their contributions are gratefully acknowledged:

  • Rich Piazza, MITRE Corporation